build: Add --enable-experimental-api configure option for unstable APIs

There are currently no unstable APIs, but some will be added in
following commits. They will be built and exposed in the libostree
global symbol list iff configured with --enable-experimental-api.

Distributions should not package OSTree with --enable-experimental-api.
This is designed for previewing new APIs on controlled platforms; any of
the APIs hidden behind this option may be changed or removed at any
point.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
Closes: #832
Approved by: cgwalters

diff --git a/Makefile-libostree.am b/Makefile-libostree.am
index 0a11488404535bd7cad4ae3dcb63aa4fea0d9df7..8d44b61cdc7ad5920adc9df46c3155057760b171 100644 (file)
--- a/Makefile-libostree.am
+++ b/Makefile-libostree.am
@@ -156,7 +156,15 @@ libostree_1_la_LIBADD = libotutil.la libglnx.la libbsdiff.la libostree-kernel-ar
 libostree_1_la_LIBADD += $(bupsplitpath)
 EXTRA_libostree_1_la_DEPENDENCIES = $(top_srcdir)/src/libostree/libostree.sym
 
-EXTRA_DIST += src/libostree/libostree.sym
+EXTRA_DIST += \
+       src/libostree/libostree.sym \
+       src/libostree/libostree-experimental.sym \
+       $(NULL)
+
+if ENABLE_EXPERIMENTAL_API
+libostree_1_la_LDFLAGS += -Wl,--version-script=$(top_srcdir)/src/libostree/libostree-experimental.sym
+EXTRA_libostree_1_la_DEPENDENCIES += $(top_srcdir)/src/libostree/libostree-experimental.sym
+endif
 
 if USE_LIBARCHIVE
 libostree_1_la_CFLAGS += $(OT_DEP_LIBARCHIVE_CFLAGS)

diff --git a/Makefile-tests.am b/Makefile-tests.am
index ab7750d22cc3405051cbd7e6797ab09ba4189baa..14e30b4659c6e8703d5dee071c667678340daeef 100644 (file)
--- a/Makefile-tests.am
+++ b/Makefile-tests.am
@@ -34,6 +34,7 @@ TESTS_ENVIRONMENT += OT_TESTS_DEBUG=1 \
        GI_TYPELIB_PATH=$$(cd $(top_builddir) && pwd)$${GI_TYPELIB_PATH:+:$$GI_TYPELIB_PATH} \
        LD_LIBRARY_PATH=$$(cd $(top_builddir)/.libs && pwd)$${LD_LIBRARY_PATH:+:$${LD_LIBRARY_PATH}} \
        PATH=$$(cd $(top_builddir)/tests && pwd):$${PATH} \
+       OSTREE_FEATURES="$(OSTREE_FEATURES)" \
        $(NULL)
 if BUILDOPT_ASAN
 TESTS_ENVIRONMENT += OT_SKIP_READDIR_RAND=1 G_SLICE=always-malloc

diff --git a/apidoc/Makefile.am b/apidoc/Makefile.am
index 730a4c3310236013602abad98ed2b1f16228099c..f3405fb0794e881fede6f47d486361faaac4df0e 100644 (file)
--- a/apidoc/Makefile.am
+++ b/apidoc/Makefile.am
@@ -120,6 +120,7 @@ include $(top_srcdir)/gtk-doc.make
 EXTRA_DIST += \
        version.xml \
        ostree-sections.txt \
+       ostree-experimental-sections.txt \
        $(NULL)
 
 -include $(top_srcdir)/git.mk

diff --git a/apidoc/ostree-experimental-sections.txt b/apidoc/ostree-experimental-sections.txt
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/configure.ac b/configure.ac
index dbcc99ea867205d58c322109c6751439fa308229..6acd0b3c77293293e2b11dbccdaa6832412dec0d 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -429,6 +429,22 @@ AS_IF([test "x$found_introspection" = xyes && test x$using_asan != xyes], [
 ], [have_gjs=no])
 AM_CONDITIONAL(BUILDOPT_GJS, test x$have_gjs = xyes)
 
+# Do we enable building experimental (non-stable) API?
+# The OSTREE_ENABLE_EXPERIMENTAL_API #define is used internally and in public
+# headers, so any consumer of libostree who wants to use experimental API must
+#    #define OSTREE_ENABLE_EXPERIMENTAL_API 1
+# before including libostree headers. This means the name in the AC_DEFINE below
+# is public API.
+AC_ARG_ENABLE([experimental-api],
+  [AS_HELP_STRING([--enable-experimental-api],
+                  [Enable unstable experimental API in libostree [default=no]])],,
+  [enable_experimental_api=no])
+AS_IF([test x$enable_experimental_api = xyes],
+  [AC_DEFINE([OSTREE_ENABLE_EXPERIMENTAL_API],[1],[Define if experimental API should be enabled])
+   OSTREE_FEATURES="$OSTREE_FEATURES experimental"]
+)
+AM_CONDITIONAL([ENABLE_EXPERIMENTAL_API],[test x$enable_experimental_api = xyes])
+
 AC_CONFIG_FILES([
 Makefile
 apidoc/Makefile
@@ -461,7 +477,8 @@ echo "
     gjs-based tests:                              $have_gjs
     dracut:                                       $with_dracut
     mkinitcpio:                                   $with_mkinitcpio
-    Static compiler for ostree-prepare-root:      $with_static_compiler"
+    Static compiler for ostree-prepare-root:      $with_static_compiler
+    Experimental API                              $enable_experimental_api"
 AS_IF([test x$with_builtin_grub2_mkconfig = xyes], [
     echo "    builtin grub2-mkconfig (instead of system):   $with_builtin_grub2_mkconfig"
 ], [

diff --git a/src/libostree/libostree-experimental.sym b/src/libostree/libostree-experimental.sym
new file mode 100644 (file)
index 0000000..7ca23a1
--- /dev/null
+++ b/src/libostree/libostree-experimental.sym
@@ -0,0 +1,32 @@
+/*
+ * Copyright © 2017 Endless Mobile, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Authors:
+ *  - Philip Withnall <withnall@endlessm.com>
+ */
+
+/* Symbols in this file are added to the build if OSTree is configured with
+ * --enable-experimental-api. They are not stable or officially supported, and
+ * might disappear or change in future releases. */
+
+/*
+LIBOSTREE_2017.6_EXPERIMENTAL {
+global:
+  some_symbol;
+} LIBOSTREE_2017.6;
+*/

diff --git a/tests/test-symbols.sh b/tests/test-symbols.sh
index 55157c07c4731dd7306d1af8daa1b499045af1e5..3ee018b0d1a8188f5dd3c5c8dc57705396d9ff7e 100755 (executable)
--- a/tests/test-symbols.sh
+++ b/tests/test-symbols.sh
@@ -21,9 +21,17 @@ set -euo pipefail
 
 echo '1..2'
 
+if echo "$OSTREE_FEATURES" | grep --quiet --no-messages "experimental"; then
+  experimental_sym="${G_TEST_SRCDIR}/src/libostree/libostree-experimental.sym"
+  experimental_sections="${G_TEST_SRCDIR}/apidoc/ostree-experimental-sections.txt"
+else
+  experimental_sym=""
+  experimental_sections=""
+fi
+
 echo "Verifying all expected symbols are actually exported..."
-grep ' ostree_[A-Za-z0-9_]*;' ${G_TEST_SRCDIR}/src/libostree/libostree.sym | sed -e 's,^ *\([A-Za-z0-9_]*\);,\1,' | sort -u > expected-symbols.txt
-eu-readelf -a ${G_TEST_BUILDDIR}/.libs/libostree-1.so | grep 'FUNC.*GLOBAL.*DEFAULT.*@@LIBOSTREE_' | sed -e 's,^.* \(ostree_[A-Za-z0-9_]*\)@@LIBOSTREE_[0-9_.]*,\1,' |sort -u > found-symbols.txt
+grep --no-filename ' ostree_[A-Za-z0-9_]*;' ${G_TEST_SRCDIR}/src/libostree/libostree.sym $experimental_sym | sed -e 's,^ *\([A-Za-z0-9_]*\);,\1,' | sort -u > expected-symbols.txt
+eu-readelf -a ${G_TEST_BUILDDIR}/.libs/libostree-1.so | grep 'FUNC.*GLOBAL.*DEFAULT.*@@LIBOSTREE_' | sed -e 's,^.* \(ostree_[A-Za-z0-9_]*\)@@LIBOSTREE_[0-9A-Z_.]*,\1,' |sort -u > found-symbols.txt
 diff -u expected-symbols.txt found-symbols.txt
 echo "ok exports"
 
@@ -31,7 +39,7 @@ echo "ok exports"
 grep -E -v '(ostree_cmd__private__)|(ostree_fetcher_config_flags_get_type)' found-symbols.txt > expected-documented.txt
 
 echo "Verifying all public symbols are documented:"
-grep '^ostree_' ${G_TEST_SRCDIR}/apidoc/ostree-sections.txt |sort -u > found-documented.txt
+grep '^ostree_' ${G_TEST_SRCDIR}/apidoc/ostree-sections.txt $experimental_sections |sort -u > found-documented.txt
 diff -u expected-documented.txt found-documented.txt
 
 echo 'ok documented symbols'